docs: document compaction and image model selection - #8348

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

Thanks for the PR!

Template looks good ✓ — all required sections present, including the bilingual body.

Problem: this is a genuine documentation gap, not a theoretical one. The compactionModel and imageModel settings already ship and are exposed by the settings schema, but the user docs only covered the fast/voice/vision model paths — so there was no way to discover how to configure a dedicated compression model or why image generation stays unavailable without a valid image-only route. Observed gap, correctly scoped.

Direction: aligned. This documents already-shipped behavior with no runtime change, which is squarely in scope. It touches model selection only descriptively (no logic changes), so no escalation needed.

Size: not applicable — docs-only, 2 files under docs/, 14 additions / 0 deletions. No core paths touched.

Approach: the scope feels right. Two focused additions — a compactionModel and an imageModel entry in the settings reference (placed alongside the existing visionModel row, matching its table format), plus two rows in the /model command reference. Every edit serves the stated goal; no drive-by changes or scope creep.

Risk: no elevated risk signals — neither changed file matches the high-risk paths from the revert-history analysis.

Moving on to code review. 🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 138f2661808954caad2c6df8bafc95f63224648d · re-run with @qwen-code /triage}

Code review

For a docs PR the review is really an accuracy check, so I read the PR title + motivation and formed my own baseline first: I'd add a compactionModel and an imageModel row to the settings reference (matching the existing visionModel/fastModel table format) and two rows to the /model command reference. That's exactly what this PR does — no simpler path missed.

I then verified each documented claim against the shipped code:

• compactionModel — default "" matches the schema (settingsSchema.ts); "leave empty to fall back to the main model" matches Config.getCompactionModel(), which returns the main model when no override is set; "set or cleared via /model --compaction" matches the command handler, which accepts both --compaction <model-id> and --compaction clear.
• imageModel — default "" matches the schema; the "must have imageOnly: true, baseUrl, and envKey in modelProviders" requirement matches Config.resolveImageGenerationModel(), which requires imageOnly === true, a non-empty envKey, and a non-empty base URL (the modelProviders baseUrl surfaces internally as registryBaseUrl); "leave empty to keep the tool unavailable" matches getImageGenerationConfig() returning undefined when unset. The tool really is named image_gen (ToolNames.IMAGE_GEN).
• Command reference — /model --compaction <model-id>, /model --compaction clear, and /model --image <model-id> all correspond to real handler branches.

The new entries sit alongside the existing visionModel row and reuse its table structure, so they read as a natural extension rather than a bolt-on. No correctness issues, no convention violations, no scope creep. The wording is actually a touch more precise than the in-product schema description (it spells out the baseUrl/envKey requirement), which is a plus.

Nothing blocks this.

Test evidence

This is an unattended CI run, so I'm quoting the PR's own CI checks for the reviewed commit rather than running anything. Precheck passed; the load-bearing unit suite (Test (ubuntu-latest, Node 22.x)) is still in flight, and the platform matrix + integration tests are skipped — consistent with a change that touches no runtime code. No failures observed. The table below is updated in place by the finalize workflow once CI settles.

Final CI results for 138f266 (auto-updated by the triage finalize job after CI completed):

_{One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。}

No sandboxed-lane line here: this is a docs-only change with no behavioural claim to settle — the unit suite the docs reference (model-command and configuration tests) is what CI is running, and there is no runtime behaviour for /verify or /tmux to pin.

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 138f2661808954caad2c6df8bafc95f63224648d · re-run with @qwen-code /triage}

Confidence: 5/5 — clean across every stage; the docs are accurate against the shipped code and I'd merge without hesitation.

Stepping back: this is exactly the kind of PR that's easy to underrate because it's small, but it closes a real discoverability gap. The settings and /model selectors already ship, and the docs simply didn't mention them. I checked each claim against the implementation rather than taking the description at face value — defaults, the fall-back-to-main-model behavior for compaction, the imageOnly/baseUrl/envKey route requirements for image generation, and the --compaction clear syntax all match what the code actually does. The wording is even slightly more precise than the in-product schema description.

The diff is minimal and self-consistent: two settings rows that reuse the existing visionModel table format, two command rows, nothing unrelated. If I had to maintain this in six months I'd thank the author, not curse them. No reservations.

Approval is deferred only because the unit suite is still running on the reviewed commit — approval deferred until CI lands green on 138f2661808954caad2c6df8bafc95f63224648d. The finalize workflow will post the commit-pinned approval once every check completes green, and will withhold it if anything lands red or the head moves.

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 138f2661808954caad2c6df8bafc95f63224648d · re-run with @qwen-code /triage}

Review Summary — PR #8348

docs: document compaction and image model selection

Verdict: No blockers. Clean documentation-only change (+53/−39, 2 files).

What was verified

I cross-checked every factual claim in the new docs against the implementation on main:

Notes

• The commands.md diff looks large (41+/39−) but is purely column-width realignment to fit the two new /model --compaction and /model --image rows; no existing content was changed.
• New settings entries follow the same table format as the adjacent visionModel row.
• PR body is thorough (motivation, test plan, risk, bilingual summary). CI and typecheck reported green by the author.

LGTM — ship it.

@qwen-code /triage

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

— Qwen Code · sandboxed verification

Thanks for the PR!

Template looks good ✓

Problem: observed gap — compactionModel and imageModel are already shipped in the settings schema and exposed via /model --compaction / /model --image, but the user docs only covered the fast, voice, and vision model paths. Users had no way to discover these selectors from the documentation.

Direction: aligned — documenting existing, shipped features is squarely within scope. No CHANGELOG reference needed for a docs-only gap fill.

Size: not applicable (docs only, no core paths touched).

Approach: the scope feels right. Two new settings sections in settings.md and two new rows in the commands.md table — exactly the minimal set needed. The table reformatting in commands.md is mechanical (wider column to fit the longer command names) and doesn't change any existing content.

Risk: no elevated risk signals.

Moving on to code review. 🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at ce6f2d2bb6fca2da539195a720496e9c361a75d6 · re-run with @qwen-code /triage}

Code Review

Verified every documented claim against the codebase:

• compactionModel setting — exists in settingsSchema.ts with default: '', description matches. Fallback to main model confirmed in config.ts (resolveCompactionModelSelector returns this.getModel() when empty). ✓
• imageModel setting — exists in settingsSchema.ts with default: ''. The imageOnly: true + HTTPS baseUrl + envKey requirements are enforced in resolveImageGenerationModel (config.ts line ~6552) and normalizeImageGenerationBaseUrl (image-generation-service.ts rejects non-HTTPS). ✓
• /model --compaction and /model --image flags — both registered in modelCommand.ts with correct descriptions and argument hints. The clear subcommand for --compaction is implemented (persists undefined and calls config.setCompactionModel(undefined)). ✓
• Table reformatting in commands.md — purely mechanical column-width increase to accommodate the longer command names; no content changes to existing rows. ✓

No correctness issues, no convention violations, no scope creep.

Testing

N/A — documentation-only change with no user-visible behavioral impact.

All CI checks green on the reviewed commit. No failures.

— Qwen Code · qwen3.8-max-preview

_{Reviewed at ce6f2d2bb6fca2da539195a720496e9c361a75d6 · re-run with @qwen-code /triage}

Confidence: 5/5 — clean docs gap-fill, every claim verified against the implementation, CI green, nothing to second-guess.

This is exactly the kind of PR that's easy to review and easy to merge. The author identified a real documentation gap (two shipped model selectors with zero docs coverage), verified the wording against the settings schema, config resolution, and command implementation, and kept the diff to the minimum — two new settings sections and two new table rows, with only the mechanical column-width adjustment as a side effect.

I independently checked every factual claim: the compactionModel fallback semantics, the imageModel triple requirement (imageOnly, HTTPS baseUrl, envKey), the clear subcommand, and the flag registrations. All accurate. The table reformatting touches no content.

If I had to maintain this in six months, I'd thank the author — the new sections follow the exact same format as the adjacent visionModel entry, so they'll age the same way.

— Qwen Code · qwen3.8-max-preview

_{Reviewed at ce6f2d2bb6fca2da539195a720496e9c361a75d6 · re-run with @qwen-code /triage}

Released in v0.21.4.